<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<!-- saved from url=(0014)about:internet -->
<html xmlns="http://www.w3.org/1999/xhtml">

<head>

<title>
	Using JdsDriver
</title>

<link rel="stylesheet" href="_CodeDoc.css" />

<style type="text/css">
.Reference
{
	color: #003399;
}
</style>

</head>

<body id="DocBrowserTopic">

<div class="TopicHeader">
	<div class="Supertitle_">
		HomeUX Driver Collection
	</div>
	Using JdsDriver
</div>

<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<div class="Summary">

<p>This page documents how to use <b>JdsDriver</b> (in JdsDriver.dll), the HomeUX-compatible driver
that controls a JDS Technologies IR-XP2 "InfraRed Xpander", which transmits IR (infrared remote
control) codes.  <b>JdsSimulator</b> (in JdsSimulator.dll) is also documented here.</p>

<p>Page contents:</p>
<ul>
	<li><a href="#Overview">Hardware &amp; Driver Overview</a></li>
	<li><a href="#Config">Configuring JdsDriver</a></li>
	<li><a href="#Use">Using JdsDriver</a></li>
	<li><a href="#Sim">JdsSimulator</a></li>
</ul>

</div>

<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<div class="SectionHeader">
	Hardware &amp; Driver Overview<a name="Overview"></a>
</div>
<div id="DocTopic">
<div class="Section">

	<p>A <a href="http://www.jdstechnologies.com/">JDS Technologies</a> IR-XP2 "InfraRed
	Xpander"&mdash;abbreviated "JDS" in this documentation&mdash;is a device that transmits IR
	(infrared remote control) codes to 1-4 emitter ports, each of which can be connected to a
	number of transmission LEDs.</p>

	<p>JdsDriver allows a HomeUX installation to control a subset of the functionality of a JDS
	device:</p>
	<ul>

		<li>IR commands are defined, each of which specifies the address of an IR code that was
			previously programmed into the unit (programming is beyond the scope of this driver),
			as well as a play count (how many times to transmit the code) and an indication of
			which emitter ports to transmit to.</li>

		<li>The hardware can be reset.</li>

	</ul>

</div>
</div>

<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<div class="SectionHeader">
	Configuring JdsDriver<a name="Config"></a>
</div>
<div id="DocTopic">
<div class="Section">

	<p>JdsDriver is configured in the HomeUX configuration file.  Here's the general structure
	(simplified):</p>

	<table class="Grid Code">
		<col class="Column1_" />
		<tr class="Header_">
			<td class="Header1_">XML</td>
		</tr>
		<tr>
			<td class="Content_ Indent_">
				&lt;configuration&gt;
					<div>&lt;HomeUXSettings&gt;
						<div><a href="#Device">&lt;Device Driver="JdsDriver.dll"&gt;</a>
							<div><a href="#Command">&lt;Command/&gt;</a>*</div>
						</div>
						<div>&lt;/Device&gt;</div>
					</div>
					<div>&lt;/HomeUXSettings&gt;</div>
				&lt;/configuration&gt;
			</td>
		</tr>
	</table>

	<p>"<tt>*</tt>" means "zero or more allowed".</p>

	<p>Example:</p>

	<table class="Grid Code">
		<col class="Column1_" />
		<tr class="Header_">
			<td class="Header1_">XML</td>
		</tr>
		<tr>
			<td class="Content_">
	<pre>
&lt;configuration&gt;
  ...
  &lt;HomeUXSettings&gt;
    ...

    &lt;Device Name="JDS" Driver="JdsDriver.dll"
          sim:SerialPort="JdsSimulator.dll;;Test=0"
          real:SerialPort="COM11,2400,8,n,1"&gt;

      &lt;Command Name="TiVo TiVo"          Address="1"   PlayCount="1" EmitterPorts="1,2,3,4" /&gt;
      &lt;Command Name="TiVo TV Power"      Address="2"   PlayCount="1" EmitterPorts="1,2,3,4" /&gt;
      &lt;Command Name="TiVo Live TV/Guide" Address="3"   PlayCount="1" EmitterPorts="1,2,3,4" /&gt;
      &lt;Command Name="TiVo Menu"          Address="4"   PlayCount="1" EmitterPorts="1,2,3,4" /&gt;
      &lt;Command Name="TiVo Display"       Address="5"   PlayCount="1" EmitterPorts="1,2,3,4" /&gt;
      &lt;Command Name="TiVo Arrow Up"      Address="6"   PlayCount="1" EmitterPorts="1,2,3,4" /&gt;
      &lt;Command Name="TiVo Arrow Down"    Address="7"   PlayCount="1" EmitterPorts="1,2,3,4" /&gt;
      &lt;Command Name="TiVo Arrow Left"    Address="8"   PlayCount="1" EmitterPorts="1,2,3,4" /&gt;
      &lt;Command Name="TiVo Arrow Right"   Address="9"   PlayCount="1" EmitterPorts="1,2,3,4" /&gt;

    &lt;/Device&gt;

  ...
  &lt;/HomeUXSettings&gt;
&lt;/configuration&gt;
	</pre>
			</td>
		</tr>
	</table>

	<p>The following subsections describe the JdsDriver configuration file XML elements.</p>

	<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
	<div class="SubsectionHeader Reference">
		&lt;Device Driver="JdsDriver.dll"&gt;<a name="Device"></a>
	</div>
	<div class="Section">

		<p>(Required, used within <tt>&lt;HomeUXSettings&gt;</tt>.) Specifies an instance of
		JdsDriver, which is used to control a JDS device.</p>

		<div class="SubsectionHeader">Syntax</div>
		<table class="Grid Code">
			<col class="Column1_" />
			<tr class="Header_">
				<td class="Header1_">XML</td>
			</tr>
			<tr>
				<td class="Content_ Indent_">
					&lt;Device
						<div>Name="..."</div>
						<div>Driver="JdsDriver.dll"</div>
						<div>SerialPort="..."&gt;</div>
						<div><a href="#Command">&lt;Command/&gt;</a>*</div>
					&lt;/Device&gt;
				</td>
			</tr>
		</table>

		<p>"<tt>*</tt>" means "zero or more allowed".</p>

		<div class="SubsectionHeader">Attributes</div>
		<div class="Subsection">

			<div class="Subsection">
			<p class="AttributeName">Name</p>
			<p class="AttributeDescription">(String, required.)
				The name you assign to the device.
			</p>
			</div>

			<div class="Subsection">
			<p class="AttributeName">Driver</p>
			<p class="AttributeDescription">(String, required.)
				Must be "<tt>JdsDriver.dll</tt>".
			</p>
			</div>

			<div class="Subsection">
			<p class="AttributeName">SerialPort</p>
			<p class="AttributeDescription">(String, required.)
				A standard HomeUX serial port specification.  Identifies the serial port (real or
				virtual) that the hardware is connected to.  When connected to a real serial port,
				the parameters should be "<i>port-name</i>,2400,8,n,1" in order to correctly
				operate a JDS unit.
			</p>
			</div>

		</div>

	</div>

	<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
	<div class="SubsectionHeader Reference">
		&lt;Command&gt;<a name="Command"></a>
	</div>
	<div class="Section">

		<p>(Zero or more, used within <a href="#Device">&lt;Device Driver="JdsDriver.dll"&gt;</a>.)
		Specifies one JDS command.  When this command is played, a specified IR code is
		transmitted input a given number of times using the specified emitter ports.</p>

		<div class="SubsectionHeader">Syntax</div>
		<table class="Grid Code">
			<col class="Column1_" />
			<tr class="Header_">
				<td class="Header1_">XML</td>
			</tr>
			<tr>
				<td class="Content_ Indent_">
					&lt;Command
						<div>Name="..."</div>
						<div>Address="..."</div>
						<div>PlayCount="..."</div>
						<div>EmitterPorts="..."</div>
					/&gt;
				</td>
			</tr>
		</table>

		<div class="SubsectionHeader">Attributes</div>
		<div class="Subsection">

			<div class="Subsection">
			<p class="AttributeName">Name</p>
			<p class="AttributeDescription">(String, required.)
				The name you assign to the command.
			</p>
			</div>

			<div class="Subsection">
			<p class="AttributeName">Address</p>
			<p class="AttributeDescription">(Integer, required.)
				The address of the IR code to transmit, from 1 to the maximum number of IR codes,
				inclusive.</p>
			</div>

			<div class="Subsection">
			<p class="AttributeName">PlayCount</p>
			<p class="AttributeDescription">(Integer, required.)
				The number of times to transmit the IR code when the command is played.</p>
			</div>

			<div class="Subsection">
			<p class="AttributeName">EmitterPorts</p>
			<p class="AttributeDescription">(Comma-separated integers, required.)
				The IR port(s) to transmit the IR code through; e.g. "1,2,3,4".</p>
			</div>

		</div>

	</div>

</div>
</div>

<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<div class="SectionHeader">
	Using JdsDriver<a name="Use"></a>
</div>
<div id="DocTopic">
<div class="Section">

	<p>JdsDriver implements the following SyncPath schema:</p>
	<ul>

		<li><b><tt><i>device-name</i>\Commands\<i>command-name</i></tt></b><br/>
			Implements the verb "Play", which plays the specified command.</li>

	</ul>

</div>
</div>

<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<div class="SectionHeader">
	JdsSimulator<a name="Sim"></a>
</div>
<div id="DocTopic">
<div class="Section">

	<p><b>JdsSimulator</b> is a HomeUX-compatible virtual serial port implementation that simulates
	a subset of the serial communication behavior JDS hardware.  JdsSimulator performs no
	real-world actions&mdash;the simulation is purely for the purposes of testing a HomeUX
	installation without having to connect to real hardware.</p>

	<p>To use JdsSimulator in HomeUX, set the SerialPort attribute of the
	<a href="#Device">&lt;Device Driver="JdsDriver.dll"&gt;</a> configuration element to a string
	with the following format:</p>

	<code class="Indent">
          JdsSimulator.dll;;Test=<i>test-number</i>
	</code>

	<p>Parameters:</p>
	<ul>

		<li><p><i>test-number</i> specifies test behavior.  This is for development use only; use 0
			to specify normal behavior.  The default is 0.</p></li>

	</ul>

	<p>You can test JdsSimulator independently of HomeUX, using the VSerial console
	application:</p>

	<code class="Indent">
          VSerial.exe -echo -dll JdsSimulator.dll;;Test=<i>test-number</i>
	</code>

	<p>JdsSimulator implements a limited simulation&mdash;only the following hardware commands are
	currently supported.  (See JDS hardware documentation for information about hardware commands
	and notifications.)</p>

	<p>Note that the commands may appear to be hexadecimal, but in fact they're ASCII.  For
	example, The reset command, <tt>6C82C0CC6D</tt>, is 10 ASCII characters.  Each command
	executes as soon as the last character is received&mdash;newlines are not used.</li>

	<ul>

 		<li><p>Reset: Syntax:</p>
			<ul>
				<li><tt>6C82C0CC6D</tt></li>
			</ul>
			<p>Resets the simulated hardware.</p></li>

 		<li><p>Play IR code: Syntax (14 ASCII characters, each of which is an uppercase hexadecimal
			digit, with no spaces):</p>
			<ul>
				<li><tt>6C85<i>(memory)</i><i>(address)</i><i>(play-count)</i><i>(emitter-ports)</i>CC</tt></li>
			</ul>
			<p><i>(memory)</i> is "F5" for the lower memory bank (first 250 IR code), "F7" for the
			upper memory bank (second 250 IR codes); <i>(address)</i> is the IR code address (1 to
			250, inclusive, specified as a 2-digit uppercase hexadecimal number); <i>(play-count)</i>
			is the number of times to transmit the IR code, specified as a 2-digit uppercase
			hexadecimal number); <i>(emitter-ports)</i> indicates the emitter ports to use, specified
			as a 2-digit uppercase hexadecimal number, where the low-order bit is the first port,
			the next bit is the next port, etc.</p></li>

	</ul>

</div>
</div>

<!-- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -->
<div class="TopicFooter">
</div>

<div class="PageFooter">
<p>See <a href="http://www.HomeUX.org">http://www.HomeUX.org</a> for more information about HomeUX.</p>
</div>

</body>

</html>

